fix(objectql): the value-shape detail prescribes the key rename, not the missing-pair type error - #16078

Fixes #15490

An operator running os migrate value-shapes over real legacy location data was told Invalid input: expected number, received undefined and left to derive a rename that edit distance cannot reach — while LocationValueSchema had already built the prescription (latitude -> lat) and thrown it away.

All evidence below is from commit 290dfc53f.

The defect

A value-shape rejection was read positionally, parsed.error.issues[0], at two sites — the card names one:

zod reports per-member issues before the object-level unrecognized_keys one, so on a value whose keys were renamed the actionable message sorts last. Fixing only the second site would have left the first emitting the identical wrong prescription — which is exactly the drift the comment at :840 already worries about, so both now share one reader.

Deliverable 1 — the sweep, done first, and it changed what shipped

The card fenced its own suggestion: confirm the positional read does not mislead the other structured-JSON classes before changing it. Every class the two readers cover was measured through the real valueSchemaFor, with a battery per class (missing members, undeclared keys, both at once, wrong base type):

16 classes measured; 2 can emit unrecognized_keys at all. Only location and address are backed by a key-closed object schema. The reference and file-reference classes are strings, composite / record / repeater / vector are open records and arrays, json is z.unknown(), and the one deliberately loose object shape (FileValueSchema) never refuses a key.

So preferring unrecognized_keys is a no-op for the other fourteen — it cannot change a single character of their diagnosis, which is what makes it safe as a blanket rule rather than merely untested against them. And both classes it does reach curate an aliases map, so the undeclared key is the half carrying the prescription in both.

The sweep refuted the reason address looked immune

The triage read was that address declares every member optional, so no invalid_type can sort ahead of the undeclared-key issue. Measured, that holds only for the missing-member route. A wrong-typed declared member still emits invalid_type, and it still sorts first:

address  { street: 5, postal_code: '98101' }
  issues[0] invalid_type       path=['street']  Invalid input: expected string, received number
  issues[1] unrecognized_keys  path=[]          ... Did you mean `postal_code` -> `postalCode`? ...

So the defect reaches address too; the contrast case that made it look location-only just happened to carry no type error. That case is now pinned.

End-to-end, through the real exported scanValueShapes

blocking counts are identical before and after in every case.

Finishing the pin

scan-value-shapes.test.ts already used the exact value { geo: { latitude: 1, longitude: 2 } } and asserted only report.blocking === 1 — never detail. The fixture was there; only the assertion was missing, which is why no gate could see this. It now asserts the prescription, and names the string that was being shown instead so a regression to the positional read is visible.

Ablation (one shell; mutation proven on disk before measuring, restore proven after):

mutate both sites back to positional:
  injected positional reads = 2 (expect 2), remaining helper calls = 0 (expect 0)
  mutated blob d34e3809... != HEAD blob 08f474fd...      <- mutation confirmed on disk
green leg (fix in place)    exit=0    Test Files 1 passed (1)   Tests 9 passed (9)
red leg   (mutated)         exit=1    Test Files 1 failed (1)   Tests 2 failed | 7 passed (9)
    x #15490: an undeclared key outranks a same-value member error - on address too
        AssertionError: expected 'Invalid input: expected string, recei...' to contain '`postal_code` -> `postalCode`'
    x the scan counts exactly what strict mode rejects - one predicate, not two
        AssertionError: expected 'Invalid input: expected number, recei...' to contain '`latitude` -> `lat`'
restore: blob == HEAD blob AND `git diff HEAD` empty AND index clean
green leg (restored)        exit=0    Test Files 1 passed (1)   Tests 9 passed (9)
VERDICT: ABLATION VALID - the pin CAN see this defect.

The 7 tests that passed in both legs are every blocking count and every accept/reject assertion — reverting the fix moved no verdict, which is the same fact from the other direction.

No verdict moves

The same values are flagged, the same writes rejected or admitted, and the deployment gate opens on the same evidence. The helper is only reached after the parsed.success branch, so the accept/reject decision never consults it. Only operator-facing text changes: the scan finding's detail, the warn-first [value-shape] log line, and the invalid_value_shape error's detail under strict enforcement.

Clause-2: no — both limbs measured separately on @objectstack/objectql's built surface.

• Does any exported symbol or signature move? No. Built at head, swapped both changed sources back to base c463d03e0, rebuilt, diffed dist/index.d.ts. With the content-hash chunk filename normalized (util-D3s8yRSa -> util-mkEsVIjj, which moves because implementation bytes changed), the only remaining difference is the JSDoc on ValueShapeFinding.detail. Declared-symbol sets are identical, 116 vs 116. valueShapeDetail is module-private and appears 0 times in the emitted .d.ts. The base rebuild was byte-identical to a snapshot taken before any edit, which confirms the base artifact. Restore proven byte-exact, and a final rebuild put dist/ back to the head artifact.
• Is any request newly accepted or rejected? No, per the ablation's shared-pass set above.

Verification (all at 290dfc53f)

• pnpm --filter @objectstack/objectql exec vitest run --maxWorkers=2 src/validation/scan-value-shapes.test.ts src/validation/record-validator.test.ts — Test Files 2 passed (2), Tests 104 passed (104)
• pnpm --filter @objectstack/objectql typecheck — exit 0, all three legs; check:test-typecheck: OK — 44 file(s) / 242 error(s) / 69 pinned signature(s) held (ledger unmoved)
• pnpm lint (whole repo, eslint . --no-inline-config) — exit 0
• Gate family re-derived after the final commit with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, provenance line checked: "gate list derived from the tree of 'objectstack-ai/objectstack' at commit 290dfc5". All 57 run: 55 exit 0; the 2 non-zero are both exit 3 = PREREQUISITE NOT MET, which each gate documents as "NOT a pass and NOT a finding":
  • check:dual-build-cjs-loads — reads built output for 54 packages with no dist/; its own --self-test passed 93 cases
  • check:type-check-debt — needs the whole workspace build closure. The targeted answer is the package typecheck above, green with its debt ledger unmoved

CI runs both with the full build.

Out of scope

packages/spec/src/data/default-value-shape.ts:120 carries a third positional issues[0] read producing a detail string. It is a different function on the defaultValue authoring path rather than the stored-value path this card governs, so it is not touched here. Filed separately as #16077, with the measurement.

Generated by Claude Code